Inside Macintosh: Memory
The Memory Manager provides several routines for initializing and resizing heap zones.
To obtain information about the current application partition, applications can call the GetApplLimit function and the TopMem function. If your application uses the stack extensively, you might want to ensure that the stack is set to at least some minimum size, at the expense of the heap. To do so, use the SetApplLimit procedure to change the application heap limit before you call the MaxApplZone procedure.
To initialize a new heap zone, use the InitZone procedure. The Operating System automatically initializes the application zone by calling the SetApplBase procedure, which subsequently calls the InitApplZone procedure.
Use the GetApplLimit function to get the application heap limit, beyond which the application heap cannot expand.
FUNCTION GetApplLimit: Ptr;
The GetApplLimit function returns the current application heap limit. The Memory Manager expands the application heap only up to the byte preceding this limit.
Nothing prevents the stack from growing below the application limit. If the Operating System detects that the stack has crashed into the heap, it generates a system error. To avoid this, use GetApplLimit and the SetApplLimit procedure to set the application limit low enough so that a growing stack does not encounter the heap.
The GetApplLimit function does not indicate the amount of memory available to your application.
Use the SetApplLimit procedure to set the application heap limit, beyond which the application heap cannot expand.
PROCEDURE SetApplLimit (zoneLimit: Ptr);
The SetApplLimit procedure sets the current application heap limit to zoneLimit . The Memory Manager then can expand the application heap only up to the byte preceding the application limit. If the zone already extends beyond the specified limit, the Memory Manager does not cut it back but does prevent it from growing further.
The zoneLimit parameter is not a byte count, but an absolute byte in memory. Thus, you should use the SetApplLimit procedure only with a value obtained from the Memory Manager functions GetApplLimit or ApplicationZone .
You cannot change the limit of zones other than the application heap zone.
To find out the location of the top of an application's partition, you can use the TopMem function, which exhibits special behavior during the startup process.
FUNCTION TopMem: Ptr;
Except during the startup process, the TopMem function returns a pointer to the byte at the top of an application's partition, directly above the jump table. The function does this to maintain compatibility with programs that check TopMem to find out how much memory is installed in a computer. To obtain this information, you can currently use the Gestalt function.
The function exhibits special behavior at startup time, and the value it returns controls the amount by which an extension can lower the value of the global variable BufPtr at startup time. If you are writing a system extension, you should not lower the value of BufPtr by more than MemTop DIV 2 + 1024 . If you do lower BufPtr too far, the startup process generates an out-of-memory system error.
You should never need to call TopMem except during the startup process.
If you want to use heap zones other than the original application heap zone, a temporary memory zone, or the system heap zone, you can use the InitZone procedure to initialize a new heap zone.
PROCEDURE InitZone (pGrowZone: ProcPtr; cMoreMasters: Integer;
limitPtr, startPtr: Ptr);
The InitZone procedure creates a new heap zone, initializes its header and trailer, and makes it the current zone. Although the new zone occupies memory addresses from startPtr through limitPtr-1 , the new zone includes a zone header and a zone trailer. In addition, the new zone contains a block header for the master pointer block and 4 bytes for each master pointer. If you need to create a zone with some specific number of usable bytes, see "Organization of Memory," beginning on Organization of Memory , for details on the sizes of the zone header, zone trailer, and block header.
The sizes of zones and block headers may change in future system software versions. You should ensure that your zones are large enough to accommodate a reasonable increase in the sizes of those structures.
Because InitZone changes the current zone, you should not call it at interrupt time.
The Process Manager calls the InitApplZone procedure indirectly when it starts up your application. You should never need to call it. It is documented for completeness only.
PROCEDURE InitApplZone;
The InitApplZone procedure initializes the application heap zone and makes it the current zone. The Memory Manager discards the contents of any previous application zone and discards all previously existing blocks in that zone. The procedure sets the zone's grow-zone function to NIL .
Reinitializing the application zone from within a running program is dangerous, because the application's code itself normally resides in the application zone. To do so safely, you must make sure that the code containing the InitApplZone call is not in the application zone.
You should not call InitApplZone at all, but, if you must, be sure not to call it at interrupt time because it could purge and allocate memory.
The Process Manager calls the SetApplBase procedure when it starts up your application. You should never need to call it. It is documented for completeness only.
PROCEDURE SetApplBase (startPtr: Ptr);
The SetApplBase procedure sets the starting address of the application heap zone for the application being initialized to the address designated by startPtr , and then calls the InitApplZone procedure.
Like InitApplZone , SetApplBase is a potentially dangerous operation, because the program's code itself normally resides in the application heap zone. To do so safely, you must make sure that the code containing the SetApplBase call is not in the application zone.
You should not call SetApplBase at all, but, if you must, be sure not to call it at interrupt time because it affects memory.